/**
 * ***************************************************************************** Copyright (c) 2000,
 * 2009 IBM Corporation and others. All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0 which accompanies this
 * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
 *
 * <p>Contributors: IBM Corporation - initial API and implementation
 * *****************************************************************************
 */
package org.eclipse.core.resources;

import org.eclipse.core.runtime.IPath;

/**
 * A data structure returned by {@link
 * IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)} containing a
 * save number and an optional resource delta.
 *
 * @see IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface ISavedState {
  /**
   * Returns the files mapped with the {@link ISaveContext#map(IPath, IPath)} facility. Returns an
   * empty array if there are no mapped files.
   *
   * @return the files currently mapped by the participant
   * @see #lookup(IPath)
   * @see ISaveContext#map(IPath, IPath)
   */
  public IPath[] getFiles();

  /**
   * Returns the save number for the save participant. This is the save number of the last
   * successful save in which the plug-in <b>actively</b> participated, or <code>0</code> if the
   * plug-in has never actively participated in a successful save.
   *
   * @return the save number
   */
  public int getSaveNumber();

  /**
   * Returns the mapped location associated with the given path or <code>null</code> if none.
   *
   * @return the mapped location of a given path
   * @see #getFiles()
   * @see ISaveContext#map(IPath, IPath)
   */
  public IPath lookup(IPath file);

  /**
   * Used to receive notification of changes that might have happened while this plug-in was not
   * active. The listener receives notifications of changes to the workspace resource tree since the
   * time this state was saved. After this method is run, the delta is forgotten. Subsequent calls
   * to this method will have no effect.
   *
   * <p>No notification is received in the following cases:
   *
   * <ul>
   *   <li>if a saved state was never recorded ({@link ISaveContext#needDelta()}</code> was not
   *       called)
   *   <li>a saved state has since been forgotten (using {@link IWorkspace#forgetSavedTree(String)})
   *   <li>a saved state has been deemed too old or has become invalid
   * </ul>
   *
   * <p>All clients should have a contingency plan in place in case a changes are not available (the
   * case should be very similar to the first time a plug-in is activated, and only has the current
   * state of the workspace to work from).
   *
   * <p>The supplied event is of type {@link IResourceChangeEvent#POST_BUILD} and contains the delta
   * detailing changes since this plug-in last participated in a save. This event object (and the
   * resource delta within it) is valid only for the duration of the invocation of this method.
   *
   * @param listener the listener
   * @see ISaveContext#needDelta()
   * @see IResourceChangeListener
   */
  public void processResourceChangeEvents(IResourceChangeListener listener);
}
